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1. Generalities 

In this documentation file, we briefly describe how to run the MC@NLO package, imple- 
mented according to the formalism introduced in ref. [1]. When using MC@NLO, please 
cite refs. [1, 2]; if single-top events are generated, please also cite ref. [3]. The production 
processes now available are listed in table 1. The process codes IPR0C will be explained 
below. H\ : 2 represent hadrons (in practice, p or p). The treatment of (undecayed) vec- 
tor boson pair production within MC@NLO has been described in ref. [1], that of heavy 
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quark pair production in ref. [2]. The NLO matrix elements for these processes have been 
taken from refs. [4, 5, 6, 7]. The information given in refs. [1, 2] allows the implementa- 
tion in MC@NLO of any production process, provided that the formalism of refs. [8, 9] is 
used for the computation of cross sections to NLO accuracy. For specific information on 
single-top production, see ref. [3]. The matrix elements for Standard Model Higgs, single 
vector boson, lepton pair, associated Higgs, and single-top production have been taken 
from refs. [10, 11], ref. [12], ref. [13], ref. [14], and ref. [15] respectively. 

This documentation refers to MC@NLO version 3.3 (previous versions 1.0, 2.0, 2.2, 
2.3, 3.1, and 3.2 are described in refs. [16, 17, 18, 19, 20, 21] respectively). Decay angular 
correlations due to spin correlations in top-pair and single-top production [22] have been 
added since version 3.2; Higgs production (IPR0C=-1600-ID) now features a more sophis- 
ticated matching procedure [23] which improves the predictions for the p T spectra of the 
accompanying jets. For precise details of version changes, see app. A.1-A.7. 

1.1 Mode of operation 

In the case of standard MC, a hard kinematic configuration is generated on a event-by- 
event basis, and it is subsequently showered and hadronized. In the case of MC@NLO, all 
of the hard kinematic configurations are generated in advance, and stored in a file (which 
we call event file - see sect. 3.1); the event file is then read by HERWIG, which showers 
and hadronizes each hard configuration. Since version 2.0, the events are handled by the 
"Les Houches" generic user process interface [24] (see ref. [2] for more details). Therefore, 
in MC@NLO the reading of a hard configuration from the event file is equivalent to the 
generation of such a configuration in the standard MC. 

The signal to HERWIG that configurations should be read from an event file using the 
Les Houches interface is a negative value of the process code IPR0C; this accounts for the 
negative values in table 1. In the case of heavy quark pair, Higgs, Higgs in association with 
a W or Z, and lepton pair (through Z/7* exchange) production, the codes are simply the 
negative of those for the corresponding standard HERWIG MC processes. Where possible, 
this convention will be adopted for additional MC@NLO processes. Consistently with what 
happens in standard HERWIG, by subtracting 10000 from IPROC one generates the same 
processes as in table 1, but eliminates the underlying event 1 . 

Higgs decays are controlled in the same way as in HERWIG, that is by adding -ID to 
the process code. The conventions for ID are the same as in HERWIG, namely ID = 1 ... 6 
for uu . . . tt; 7 ... 9 for e + e~ . . . t + t~; 10, 11 for W + W~ , ZZ; and 12 for 77. Furthermore, 
ID = gives quarks of all flavours, and ID = 99 gives all decays. 

Process codes IPR0C=-1360-IL and -1370-IL do not have an analogue in HERWIG; 
they are the same as — 1350— IL, except for the fact that only a Z or a 7* respectively is 
exchanged. The value of IL determines the lepton identities, and the same convention as in 
HERWIG is adopted: IL=1, . . . , 6 for Ztl = e, v e , fj,, v^t, v t respectively. At variance with 
HERWIG, IL cannot be set equal to zero. Process codes IPR0C=-1460-IL and -1470-IL 
are the analogue of HERWIG 1450+IL; in HERWIG either W + or W~ can be produced, 

lr The same effect can be achieved by setting the HERWIG parameter PRS0F = 0. 
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whereas MC@NLO treats the two vector bosons separately. For these processes, as in 
HERWIG, IL=1,2,3 for Ztl = r, but again the choice IL = is not allowed. 
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Table 1: Processes implemented in MC@NLO 3.3. H° denotes the Standard Model Higgs boson 
and the value of ID controls its decay, as described in the HERWIG manual and below. The values 
of IV, IL, ILi, and IL2 control the identities of vector bosons and leptons, as described below. In 
singlc-t production, the value of IC controls the production processes, as described below. IPR0C- 
10000 generates the same processes as IPRDC, but eliminates the underlying event. A void entry 
indicates that the corresponding variable is unused. The 'Spin' column indicates whether spin 
correlations in vector boson or top decays are included (/), neglected (x) or absent (void entry). 
Spin correlations in Higgs decays are included by HERWIG (e.g. in H° — > W + W~ — > l + vl~v). 
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The lepton pair processes IPRDC=— 1350— IL, . . ., — 1470— IL include spin correla- 
tions when generating the angular distributions of the produced leptons. However, if 
spin correlations are not an issue, the single vector boson production processes IPR0C= 
— 1396,— 1397, — 1497,— 1498 can be used, in which case the vector boson decay products 
are distributed according to phase space. 

There are a number of other differences between the lepton pair and single vector 
boson processes. The latter do not feature the 7— Z interference terms. Also, their cross 
sections are fully inclusive in the final-state fermions resulting from 7*, Z or W^. The 
user can still select a definite decay mode using the variable M0DB0S (see sect. 3.2), but the 
relevant branching ratio will not be included automatically by MC@NLO. In the case of 7* 
production, the branching ratios are Cjg?/(20/3), % being the electric charge (in units of 
the positron charge) of the fermion i selected through M0DB0S, and Cj = 1 for leptons and 
3 for quarks. Notice that 20/3 = Ciqf, the sum including all leptons and quarks except 
the top. Thus, the total rate predicted by MC@NLO in the case of lepton pair production 
can also be recovered by multiplying the corresponding single vector boson total rate by 
the relevant branching ratio. 

In NLO computations for single-top production, it is customary to distinguish between 
three production mechanisms, conventionally denoted as s channel, t channel, and Wt 
mode. In version 3.3, only the former two are implemented. The user can generate them 
either separately, by setting IC=10 and IC=20 for s- and t-channel production respectively, 
or together, by setting IC=0. For example, according to table 1, t-channel single-t events 
will be generated by entering IPR0C=— 2021. 

In the case of vector boson pair production, the process codes are the negative of those 
adopted in MC@NLO 1.0 (for which the Les Houches interface was not yet available), 
rather than those of standard HERWIG. 

Furthermore, in the case of ti, sin gle-t, H°W ± , H°Z and W + W~ production, the 
value of IPR0C alone may not be sufficient to fully determine the process type (including 
decay products), and new variables IV, ILi, and IL2 have been introduced (see table 1). 
The variables ILi and IL2 can take the same values as IL relevant to lepton pair production 
(notice, however, that in the latter case IL is not an independent variable, and its value 
is included via IPR0C); in addition, IL Q =7 implies that spin correlations for the decay 
products of the corresponding particle are not taken into account, as indicated in table 1. 
More details are given in sect. 3.2. 

Apart from the above differences, MC@NLO and HERWIG behave in exactly the same 
way. Thus, the available user's analysis routines can be used in the case of MC@NLO. One 
should recall, however, that MC@NLO always generates some events with negative weights 
(see refs. [1, 2]); therefore, the correct distributions are obtained by summing weights with 
their signs (i.e., the absolute values of the weights must NOT be used when filling the 
histograms). 

With such a structure, it is natural to create two separate executables, which we 
improperly denote as NLO and MC. The former has the sole scope of creating the event 
file; the latter is just HERWIG, augmented by the capability of reading the event file. 
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1.2 Package files 

The package consists of the following files: 

• Shell utilities 
MCatNLO . Script 
MCatNLO. inputs 
Makefile 

• Utility codes 
MEcoupl . inc 
alpha . f 
dummies .f 
linux . f 
mcatnlo_date . f 
mcatnloJibook . f 
mcatnlo_helas2 . f 
mcatnloJiwdummy . f 
mcatnlo_int . f 
mcatnlo_lhauti . f 
mcatnlo_libof pdf . f 
mcatnlo_mlmtolha. f 
mcatnlo_mlmtopdf . f 
mcatnlo_pdf tomlm . f 
mcatnlo_str . f 
mcatnlo_uti . f 
mcatnlo_uxdate . c 
sun.f 

trapf pe . c 

• General HERWIG routines 
mcatnloJiwdriver . f 
mcatnlojiwlhin . f 

• Process-specific codes 
mcatnloJiwanbtm . f 
mcatnloJiwanhgg . f 
mcatnloJiwanllp . f 
mcatnloJiwantop . f 
mcatnlojiwanstp . f 
mcatnloJiwansvb . f 
mcatnloJiwanvbp . f 
mcatnloJiwanvhg . f 
mcatnloJigmain . f 
mcatnloJigxsec . f 
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mcatnlo_llmain . f 
mcatnlo_llxsec . f 
mcatnlo_qqmain . f 
mcatnlo_qqxsec . f 
mcatnlo_sbmain . f 
mcatnlo_sbxsec . f 
mcatnlo_stmain . f 
mcatnlo_stxsec . f 
mcatnlo_vbmain . f 
mcatnlo_vbxsec . f 
mcatnlo_vhmain . f 
mcatnlo_vhxsec . f 
hgscblks .h 
hvqcblks .h 
llpcblks .h 
stpcblks .h 
svbcblks .h 
vhgcblks .h 



These files can be downloaded from the web page: 

http : //www. hep .phy . cam. ac .uk/theory/webber/MCatNLO 
The files mcatnloJiwancccccc. f , which appear in the list of the process-specific codes, are 
sample HERWIG analysis routines. They are provided here to give the user a ready-to-run 
package, but they should be replaced with appropriate codes according to the user's needs. 

In addition to the files listed above, the user will need a version of the HERWIG code 
[25, 26, 27]. As stressed in ref. [1], for the MC@NLO we do not modify the existing (LL) 
shower algorithm. However, since MC@NLO versions 2.0 and higher make use of the Les 
Houches interface, first implemented in HERWIG 6.5, the version must be 6.500 or higher. 
On most systems, users will need to delete the dummy subroutines UPEVNT, UPINIT, 
PDFSET and STRUCTM from the standard HERWIG package, to permit linkage of the 
corresponding routines from the MC@NLO package. As a general rule, the user is strongly 
advised to use the most recent version of HERWIG (currently 6.510 - with versions lower 
than 6.504 problems can be found in attempting to specify the decay modes of single vector 
bosons through the variable M0DB0S. Also, crashes in the shower phase have been reported 
when using HERWIG 6.505, and we therefore recommend not to use that version). 

1.3 Working environment 

We have written a number of shell scripts and a Makefile (all listed under Shell utilities 
above) which will simplify the use of the package considerably. In order to use them, the 
computing system must support bash shell, and gmake 2 . Should they be unavailable on the 
user's computing system, the compilation and running of MC@NLO requires more detailed 

2 For Macs running under OSX vlO or higher, make can be used instead of gmake. 
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instructions; in this case, we refer the reader to app. B. This appendix will serve also as a 
reference for a more advanced use of the package. 

1.4 Source and running directories 

We assume that all the files of the package sit in the same directory, which we call the 
source directory. When creating the executable, our shell scripts determine the type of 
operating system, and create a subdirectory of the source directory, which we call the 
running directory, whose name is Alpha, Sun, Linux, or Darwin, depending on the operating 
system. If the operating system is not known by our scripts, the name of the working 
directory is Run. The running directory contains all the object files and executable files, 
and in general all the files produced by the MC@NLO while running. It must also contain 
the relevant grid files (see sect. 2.1), or links to them, if the library of parton densities 
provided with the MC@NLO package is used. 

2. Prior to running 

Before running the code, the user needs to edit the following files: 
mcatnlo Jiwancecea;. f 
mcatnlo Jiwdriver . f 
mcatnlo Jiwlhin . f 

We do not assume that the user will adopt the latest release of HERWIG (although, as ex- 
plained above, it must be version 6.500 or higher). For this reason, the files mcatnloJiwdriver . f 
and mcatnloJiwlhin.f must be edited, in order to modify the INCLUDE HERWIGXX.INC 
command to correspond to the version of HERWIG the user is going to adopt. mcatnloJiwdriver . f 
contains a set of read statements, which are necessary for the MC to get the input pa- 
rameters (see sect. 3 for the input procedure); these read statements must not be modi- 
fied or eliminated. Also, mcatnloJiwdriver . f calls the HERWIG routines which perform 
showering, hadronization, decays (see sect. 3.2 for more details on this issue), and so 
forth; the user can freely modify this part, as customary in MC runs. Finally, the sample 
codes mcatnlo Jiwancccccc. f contain analysis-related routines: these files must be replaced 
by files which contain the user's analysis routines. We point out that, since version 2.0, 
the Makefile need not be edited any longer, since the corresponding operations are now 
performed by setting script variables (see sect. 4). 

2.1 Parton densities 

Since the knowledge of the parton densities (PDF) is necessary in order to get the physical 
cross section, a PDF library must be linked. The possibility exists to link the (now obsolete) 
CERNLIB PDF library (PDFLIB), or its replacement LHAPDF [28]; however, we also 
provide a self-contained PDF library with this package, which is faster than PDFLIB, and 
contains PDF sets released after the last and final PDFLIB version (8.04; most of these 
sets are now included in LHAPDF). A complete list of the PDFs available in our PDF 
library can be downloaded from the MC@NLO web page. The user may link one of the 
three PDF libraries; all that is necessary is to set the variable PDFLIBRARY (in the file 
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MCatNLD . inputs) equal to THISLIB if one wants to link to our PDF library, and equal to 
PDFLIB or to LHAPDF if one wants to link to PDFLIB or to LHAPDF. Our PDF library 
collects the original codes, written by the authors of the PDF fits; as such, for most of 
the densities it needs to read the files which contain the grids that initialize the PDFs. 
These files, which can be also downloaded from the MC@NLO web page, must either be 
copied into the running directory, or defined in the running directory as logical links to the 
physical files (by using In -sn). We stress that if the user runs MC@NLO with the shell 
scripts, the logical links will be created automatically at run time. 

As stressed before, consistent inputs must be given to the NLO and MC codes. However, 
in ref. [1] we found that the dependence upon the PDFs used by the MC is rather weak. So 
one may want to run the NLO and MC adopting a regular NLL-evolved set in the former 
case, and the default HERWIG set in the latter (the advantage is that this option reduces 
the amount of running time of the MC). In order to do so, the user must set the variable 
HERPDF equal to DEFAULT in the file MCatNLO . inputs; setting HERPDF=EXTPDF will force the 
MC to use the same PDF set as the NLO code. 

Regardless of the PDFs used in the MC run, users must delete the dummy PDFLIB 
routines PDFSET and STRUCTM from HERWIG, as explained earlier. 

3. Running 

It is straightforward to run the MC@NLO. First, edit 
MCatNLO. inputs 

and write there all the input parameters (for the complete list of the input parameters, see 
sect. 4). As the last line of the file MCatNLO . inputs, write 
runMCatNLO 

Finally, execute MCatNLO . inputs from the bash shell. This procedure will create the NLO 
and MC executables, and run them using the inputs given in MCatNLO . inputs, which guar- 
antees that the parameters used in the NLO and MC runs are consistent. Should the user 
only need to create the executables without running them, or to run the NLO or the MC 
only, he/she should replace the call to runMCatNLO in the last line of MCatNLO . inputs by 
calls to 

compileNLO 

compileMC 

runNLO 

runMC 

which have obvious meanings. We point out that the command runMC may be used 
with IPR0C=1350+IL, 1450+IL, 1600+ID, 1699, 1705, 1706, 2000-2008, 2600+ID, 2699, 
2700+ID, 2799 to generate Z/j*, W ± , Higgs, bb, ti, single top, H°W or H°Z events with 
standard HERWIG (see the HERWIG manual for more details). 

We stress that the input parameters are not solely related to physics (masses, CM 
energy, and so on); there are a few of them which control other things, such as the number 
of events generated. These must also be set by the user, according to his/her needs: see 
sect. 4. 
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Two such variables are HERWIGVER and HWUTI, which were moved in version 2.0 from 
the Makefile to MCatNLO . inputs. The former variable must be set equal to the object 
file name of the version of HERWIG currently adopted (matching the one whose common 
blocks are included in the files mentioned in sect. 2). The variable HWUTI must be set equal 
to the list of object files that the user needs in the analysis routines. 

If the shell scripts are not used to run the codes, the inputs are given to the NLO or 
MC codes during an interactive talk-to phase; the complete sets of inputs for our codes are 
reported in app. B.2 for vector boson pair production. 

3.1 Event file 

The NLO code creates the event file. In order to do so, it goes through two steps; first it 
integrates the cross sections (integration step), and then, using the information gathered in 
the integration step, produces a set of hard events (event generation step). Integration and 
event generation are performed with a modified version of the SPRING-BASES package [29]. 

We stress that the events stored in the event file just contain the partons involved 
in the hard suprocesses. Owing to the modified subtraction introduced in the MC@NLO 
formalism (sec rcf. [1]) they do not correspond to pure NLO configurations, and should not 
be used to plot physical observables. Parton-level observables must be reconstructed using 
the fully-showered events. 

The event generation step necessarily follows the integration step; however, for each 
integration step one can have an arbitrary number of event generation steps, i.e., an arbi- 
trary number of event files. This is useful in the case in which the statistics accumulated 
with a given event file is not sufficient. 

Suppose the user wants to create an event file; editing MCatNLO . inputs, the user sets 
BASES=0N, to enable the integration step, sets the parameter NEVENTS equal to the number 
of events wanted on tape, and runs the code; the information on the integration step 
(unreadable to the user, but needed by the code in the event generation step) is written 
on files whose name begin with FPREFIX, a string the user sets in MCatNLO . inputs; these 
files (which we denotes as data files) have extensions .data. The name of the event file is 
EVPREFIX. events, where EVPREFIX is again a string set by the user. 

Now suppose the user wants to create another event file, to increase the statistics. The 
user simply sets BASES=0FF, since the integration step is not necessary any longer (however, 
the data files must not be removed: the information stored there is still used by the NLO 
code); changes the string EVPREFIX (failure to do so overwrites the existing event file), 
while keeping FPREFIX at the same value as before; and changes the value of RNDEVSEED 
(the random number seed used in the event generation step; failure to do so results in an 
event file identical to the previous one); the number NEVENTS generated may or may not 
be equal to the one chosen in generating the former event file(s). 

We point out that data and event files may be very large. If the user wants to store 
them in a scratch area, this can be done by setting the script variable SCRTCH equal to the 
physical address of the scratch area (see sect. 3.3). 
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3.2 Decays 

MC@NLO is intended primarily for the study of NLO corrections to production cross 
sections and distributions; NLO corrections to the decays of produced particles are not 
included. As for spin correlations, the situation in version 3.3 is summarized in table 1: 
they are included for all processes except ZZ and WZ production 3 . For the latter processes, 
quantities sensitive to the polarisation of produced particles are not given correctly even 
to leading order. For such quantities, it may be preferable to use the standard HERWIG 
MC, which does include leading-order spin correlations. 

Following HERWIG conventions, spin correlations in single-vector-boson processes are 
automatically included using the process codes (IPRDC) relevant to lepton pair production. 
In order to avoid an unnecessary proliferation of IPROC values, this strategy has not been 
adopted in other cases (tt, single-*, H Q W ± , H°Z, W + W~), in which spin correlations are 
included if the variables ILi and IL2 (the latter is used only in ti and W + W~ production) 
are given values ranging from 1 to 3 if the decaying particle is a If or a top, or from 
1 to 6 if the decaying particle is a Z . The value of IL Q determines the identity of the 
leptons emerging from the decay, and the same convention as in HERWIG is adopted (see 
the HERWIG manual and sect. 1.1). 

When IL a =7, the corresponding particle is left undecayed by the NLO code, and is 
passed as such to the MC code; the information on spin correlations is lost. However, 
the user can still force particular decay modes during the MC run. In the case of vector 
bosons, one proceeds in the same way as in standard HERWIG, using the MODBOS variables 

- see sect. 3.4 of ref. [26]. However, top decays cannot be forced in this way because the 
decay is treated as a three-body process: the boson entry in HEPEVT is for informa- 
tion only. Instead, the top branching ratios can be altered using the HWMODK subroutine 

- see sect. 7 of ref. [26]. This is done separately for the t and t. For example, CALL 
HWMODK (6,1. DO ,100 ,12 ,-11 ,5, 0,0) forces the decay t — > ^ e e + 6, while leaving t decays 
unaffected. Note that the order of the decay products is important for the decay matrix 
element (NME = 100) to be applied correctly. The relevant statements should be inserted in 
the HERWIG main program (corresponding to mcatnlo Jiwdriver . f in this package) after 
the statement CALL HWUINC and before the loop over events. A separate run with CALL 
HWM0DK(-6 , 1 .DO, 100, -12 , 11 ,-5 , 0,0) should be performed if one wishes to symmetrize 
the forcing of t and t decays, since calls to HWMODK from within the event loop do not 
produce the desired result. 

3.3 Results 

As in the case of standard HERWIG the form of the results will be determined by the user's 
analysis routines. However, in addition to any files written by the user's analysis routines, 
the MC@NLO writes the following files: 

♦ FPREFIXNLOinput: the input file for the NLO executable, created according to the set of 
input parameters defined in MCatNLO . inputs (where the user also sets the string FPREFIX). 

3 Non-factorizable spin correlations of virtual origin are not included in W + W~ , ti, and single-t produc- 
tion. See ref. [22]. 



- 10 - 



See table 2. 

♦ FPREFIXNLO . log: the log file relevant to the NLO run. 

♦ FPREFIXxxx.data: xxx can assume several different values. These are the data files 
created by the NLO code. They can be removed only if no further event generation step is 
foreseen with the current choice of parameters. 

♦ FPREFIXMCinput: analogous to FPREF I XNL input , but for the MC executable. See ta- 
ble 4. 

♦ FPREFIXMC.log: analogous to FPREFIXNLO . log, but for the MC run. 

♦ EVPREFIX. events: the event file, where EVPREFIX is the string set by the user in 
MCatNLO. inputs. 

♦ EVPREFIXxxx . events: xxx can assume several different values. These files are temporary 
event files, which are used by the NLO code, and eventually removed by the shell scripts. 
They MUST NOT be removed by the user during the run (the program will crash or give 
meaningless results). 

By default, all the files produced by the MC@NLO are written in the running directory. 
However, if the variable SCRTCH (to be set in MCatNLO . inputs) is not blank, the data and 
event files will be written in the directory whose address is stored in SCRTCH (such a 
directory is not created by the scripts, and must already exist at run time). 



4. Script variables 

In the following, we list all the variables appearing in MCatNLO . inputs; these can be 
changed by the user to suit his/her needs. This must be done by editing MCatNLO. inputs. 
For fuller details see the comments in MCatNLO . inputs. 

ECM The CM energy of the colliding particles. 

FREN The ratio between the renormalization scale, and a reference mass scale. 

FFACT As FREN, for the factorization scale. 

HVQMASS The mass (in GeV) of the top quark, except when IPR0C=-(1)1705, when it is the 
mass of the bottom quark. In this case, HVQMASS must coincide with BMASS. 

xMASS The mass (in GeV) of the particle x, with x=HGG,W,Z,U,D,S,C,B,G. 

xWIDTH The physical (Breit-Wigner) width (in GeV) of the particle x, with x=HGG,W,Z,T for 
H°, W ± , Z, and t respectively. 

IBORNHGG Valid entries are 1 and 2. If set to 1, the exact top mass dependence is retained at 
the Born level in Higgs production. If set to 2, the m t — > oo limit is used. 

xGAMMAX If xGAMMAX > 0, controls the width of the mass range for Higgs (x=H) and vector 
bosons (x=Vl,V2): the range is MASS ± (GAMMAX x WIDTH). 

xMASSINF Lower limit of the Higgs (x=H) or vector boson (x=Vl , V2) mass range; used only when 
xGAMMAX < 0. 
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xMASSSUP Upper limit of the Higgs (x=H) or vector boson (x=Vl ,V2) mass range; used only when 
xGAMMAX < 0. 

Vud CKM matrix elements, with u=U,C,T and d=D,S,B. Set VUD=VUS=VUB=0 to use 
values of PDG2003. Vud is only used in single-t production. 

AEMRUN Set it to YES to use running a em in lepton pair and single vector boson production, 
set it to NO to use a em = 1/137.0359895. 

IPROC Process number that identifies the hard subprocess: see table 1 for valid entries. 

IVCODE Identifies the nature of the vector boson in associated Higgs production. It corre- 
sponds to variable IV of table 1. 

ILxCODE Identify the nature of the leptons emerging from vector boson or top decays 
(x = 1,2). They correspond to variables ILi and IL2 of table 1. 

PARTn The type of the incoming particle #n, with n=l,2. HERWIG naming conventions are 
used (P, PBAR, N, NBAR). 

PDFGRDUP The name of the group fitting the parton densities used; the labeling conventions of 
PDFLIB are adopted. Unused when linked to LHAPDF. 

PDFSET The number of the parton density set; according to PFDLIB conventions, the pair 
(PDFGROUP, PDFSET) identifies the densities for a given particle type. When linked to 
LHAPDF, use the numbering conventions of LHAGLUE [28]. 

LAMBDAFIVE The value of A QCD , for five flavours and in the MS scheme, used in the computation 
of NLO cross sections. 

LAMBDAHERW The value of A QCD used in MC runs; this parameter has the same meaning as A QCD 
in HERWIG. 

SCHEMEOFPDF The subtraction scheme in which the parton densities are defined. 

FPREFIX Our integration routine creates files with name beginning by the string FPREFIX. 
These files are not directly accessed by the user; for more details, see sect. 3.1. 

EVPREFIX The name of the event file begins with this string; for more details, see sect. 3.1. 

EXEPREFIX The names of the NLO and MC executables begin with this string; this is useful in 
the case of simultaneous runs. 

NEVENTS The number of events stored in the event file, eventually processed by HERWIG . 

WGTTYPE Valid entries are and 1. When set to 0, the weights in the event file are ±1. When 
set to 1, they are ±u>, with w a constant such that the sum of the weights gives the 
total NLO cross section. N.B. These weights are redefined by HERWIG at MC run 
time according to its own convention (see HERWIG manual). 
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RNDEVSEED The seed for the random number generation in the event generation step; must be 
changed in order to obtain statistically-equivalent but different event files. 

BASES Controls the integration step; valid entries are ON and OFF. At least one run with 
BASES=0N must be performed (see sect. 3.1). 

PDFLIBRARY Valid entries are PDFLIB, LHAPDF, and THISLIB. In the former two case, PDFLIB 
or LHAPDF is used to compute the parton densities, whereas in the latter case the 
densities are obtained from our self-contained faster package. 

HERPDF If set to DEFAULT, HERWIG uses its internal PDF set (controlled by NSTRU), regardless 
of the densities adopted at the NLO level. If set to EXTPDF, HERWIG uses the same 
PDFs as the NLO code (see sect. 2.1). 

HWPATH The physical address of the directory where the user's preferred version of HERWIG 
is stored. 

SCRTCH The physical address of the directory where the user wants to store the data and 
event files. If left blank, these files are stored in the running directory. 

HWUTI This variables must be set equal to a list of object files, needed by the analysis routines 
of the user (for example, HWUTI=objl.o obj2.o obj3.o is a valid assignment). 

HERWIGVER This variable must to be set equal to the name of the object file corresponding to the 
version of HERWIG linked to the package (for example, HERWIGVER=herwig65 . o is a 
valid assignment). 

PDFPATH The physical address of the directory where the PDF grids are stored. Effective only 
if PDFLIBRARY=THISLIB. 

LHAPATH Set this variable equal to the name of the directory where the local version of 
LHAPDF is installed. 

LHAOFL Set LHAOFL=FREEZE to freeze PDFs from LHAPDF at the boundaries, or equal to 
EXTRAPOLATE otherwise. See LHAPDF manual for details. 
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Appendices 

A. Version changes 

A.l From MC@NLO version 1.0 to version 2.0 

In this appendix we list the changes that occurred in the package from version 1.0 to version 
2.0. 

• The Les Houches generic user process interface has been adopted. 

• As a result, the convention for process codes has been changed: MC@NLO process 
codes IPROC are negative. 

• The code mcatnlo Jiwhvvj . f , which was specific to vector boson pair production in 
version 1.0, has been replaced by mcatnlo Jiwlhin . f , which reads the event file according 
to the Les Houches prescription, and works for all the production processes implemented. 

• The Makefile need not be edited, since the variables HERWIGVER and HWUTI have 
been moved to MCatNLO . inputs (where they must be set by the user). 

• A code mcatnloJibook . f has been added to the list of utility codes. It contains a 
simplified version (written by M. Mangano) of HBOOK, and it is only used by the sample 
analysis routines mcatnloJiwancccccc. f . As such, the user will not need it when linking to a 
self-contained analysis code. 

We also remind the reader that the HERWIG version must be 6.5 or higher since the 
Les Houches interface is used. 

A. 2 From MC@NLO version 2.0 to version 2.1 

In this appendix we list the changes that occurred in the package from version 2.0 to version 
2.1. 

• Higgs production has been added, which implies new process-specific files (mcatnloJigmain . f , 
mcatnloJigxsec . f , hgscblks .h, mcatnloJiwanhgg. f ), and a modification to mcatnlo_h.wlh.in . f . 

• Post-1999 PDF sets have been added to the MC@NLO PDF library. 

• Script variables have been added to MCatNLO . inputs. Most of them are only rele- 
vant to Higgs production, and don't affect processes implemented in version 2.0. One of 
them (LAMBDAHERW) may affect all processes: in version 2.1, the variables LAMBDAFIVE and 
LAMBDAHERW are used to set the value of A QCD in NLO and MC runs respectively, whereas 
in version 2.0 LAMBDAFIVE controlled both. The new setup is necessary since modern PDF 
sets have A QCD values which are too large to be supported by HERWIG. (Recall that the 
effect of using LAMBDAHERW different from LAMBDAFIVE is beyond NLO.) 

• The new script variable PDFPATH should be set equal to the name of the directory 
where the PDF grid files (which can be downloaded from the MC@NLO web page) are 
stored. At run time, when executing runNLO, or runMC, or runMCatNLO, logical links to 
these files will be created in the running directory (in version 2.0, this operation had to be 
performed by the user manually). 

• Minor bugs corrected in mcatnloJibook. f and sample analysis routines. 
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A.3 From MCiNLO version 2.1 to version 2.2 

In this appendix we list the changes that occurred in the package from version 2.1 to version 
2.2. 

• Single vector boson production has been added, which implies new process-specific 
files (mcatnlo_sbmain.f , mcatnlo_sbxsec . f , svbcblks.h, mcatnloJiwansvb . f ), and a 
modification to mcatnlo_h.wlh.in . f . 

• The script variables WWIDTH and ZWIDTH have been added to MCatNLO . inputs. These 
denote the physical widths of the W and Z° bosons, used to generate the mass distributions 
of the vector bosons according to the Breit-Wigner function, in the case of single vector 
boson production (vector boson pair production is still implemented only in the zero-width 
approximation) . 

A.4 From MC@NLO version 2.2 to version 2.3 

In this appendix we list the changes that occurred in the package from version 2.2 to version 
2.3. 

• Lepton pair production has been added, which implies new process-specific files 
(mcatnlo_llmain.f , mcatnlo_llxsec . f , llpcblks.h, mcatnloJiwanllp . f ), and modifi- 
cations to mcatnloJiwlhin.f and mcatnloJiwdriver . f . 

• The script variable AEMRUN has been added, since the computation of single vector 
boson and lepton pair cross sections is performed in the MS scheme (the on-shell scheme 
was previously used for single vector boson production). 

• The script variables FRENMC and FFACTMC have been eliminated. 

• The structure of pseudo-random number generation in heavy flavour production has 
been changed, to avoid a correlation that affected the azimuthal angle distribution for the 
products of the hard partonic subprocesses. 

• A few minor bugs have been corrected, which affected the rapidity of the vector 
bosons in single vector boson production (a 2-3% effect), and the assignment of A QCD for 
the LO and NLO PDF sets of Alekhin. 

A. 5 From MC@NLO version 2.3 to version 3.1 

In this appendix we list the changes that occurred in the package from version 2.3 to version 
3.1. 

• Associated Higgs production has been added, which implies new process-specific files 
(mcatnlo_vhmain.f , mcatnlo_vhxsec . f , vhgcblks.h, mcatnloJiwanvhg.f ), and modifi- 
cations to mcatnloJiwlhin.f and mcatnloJiwdriver . f. 

• Spin correlations in W + W~ production and leptonic decay have been added; the 
relevant codes (mcatnlo_vpmain.f , mcatnlo_vhxsec . f ) have been modified; the sample 
analysis routines (mcatnloJiwanvbp . f ) have also been changed. Tree-level matrix elements 
have been computed with MadGraph/MadEvent [30, 31], which uses HELAS [32]; the 
relevant routines and common blocks are included in mcatnlo Jielas2 . f and MEcoupl . inc. 

• The format of the event file has changed in several respects, the most relevant of 
which is that the four-momenta are now given as {pxiPyiPz-,™) (up to version 2.3 we had 
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iPxiPyiPzi Ei))- Event files generated with version 2.3 or lower must not be used with version 
3.1 or higher (the code will prevent the user from doing so). 

• The script variables GAMMAX, MASS INF, and MASSSUP have been replaced with xGAMMAX, 
xMASSINF and xMASSSUP, with x=H,Vl,V2. 

• New script variables IVCODE, IL1C0DE, and IL2C0DE have been introduced. 

• Minor changes have been made to the routines that put the partons on the HERWIG 
mass shell for lepton pair, heavy quark, and vector boson pair production; effects are 
beyond the fourth digit. 

• The default electroweak parameters have been changed for vector boson pair pro- 
duction, in order to make them consistent with those used in other processes. The cross 
sections are generally smaller in version 3.1 wrt previous versions, the dominant effect being 
the value of sin 9 W : we have now sin 2 9 W = 0.2311, in lower versions sin 2 9 W = 1 — rn^/m^- 
The cross sections are inversely proportional to sin c7 w . 

A.6 From MC@NLO version 3.1 to version 3.2 

In this appendix we list the changes that occurred in the package from version 3.1 to version 
3.2. 

• Single-i production has been added, which implies new process-specific files (mcatnlo_stmain. f , 
mcatnlo_stxsec . f , stpcblks .h, mcatnloJiwanstp . f ), and modifications to mcatnloJiwlhin . f 

and mcatnloJiwdriver . f . 

• LHAPDF library is now supported, which implies modifications to all *main.f files, 
and two new utility codes, mcatnlo_lhauti . f and mcatnlojnlmtolha.f . 

• New script variables Vud, LHAPATH, and LHAOFL have been introduced. 

• A bug affecting Higgs production has been fixed, which implies a modification to 
mcatnloJigxsec . f . Cross sections change with respect to version 3.1 only i/FFACT/ 1 (by 
0(1%) in the range 1/2 < FFACT < 2). 

A.7 From MCiNLO version 3.2 to version 3.3 

In this appendix we list the changes that occurred in the package from version 3.2 to version 
3.3. 

• Spin correlations have been added to tt and single-i production processes, which imply 
modifications to several codes (mcatnlo_qqmain. f , mcatnlo_qqxsec . f , mcatnlo_stmain. f , 
mcatnlo_stxsec . f , mcatnloJiwlhin . f and mcatnloJiwdriver . f). Tree- level matrix ele- 
ments have been computed with MadGraph/MadEvent [30, 31]. 

• The matching between NLO matrix elements and parton shower is now smoother 
in Higgs production (see ref. [23]), which helps eliminate one unphysical feature in the p T 
spectra of the accompanying jets. The code mcatnlo Jigmain . f has been modified. 

• The new script variable TWIDTH has been introduced. 

• All instances of HWWARN( ' s ' , i , *n) have been replaced with HWWARN (' s' ,i) in 
HERWIG-related codes. This is consistent with the definition of HWWARN in HERWIG ver- 
sions 6.510 and higher; the user must be careful if linking to HERWIG versions, in which the 
former form of HWWARN is used. Although HERWIG 6.510 compiles with g95 or gf ortran, 
MC@NLO 3.3 does not. 
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B. Running the package without the shell scripts 

In this appendix, we describe the actions that the user needs to take in order to run the 
package without using the shell scripts, and the Makefile. Examples are given for vector 
boson pair production, but only trivial modifications are necessary in order to treat other 
production processes. 

B.l Creating the executables 

An MC@NLO run requires the creation of two executables, for the NLO and MC codes 
respectively. The files to link depend on whether one uses PDFLIB, LHAPDF, or the PDF 
library provided with this package; we list them below: 

• NLO with private PDFs: mcatnlo_vbmain . o mcatnlo_vbxsec . o mcatnlo_helas2 . o 
mcatnlo_date . o mcatnlo_int . o mcatnlo_uxdate . o mcatnlo_uti . o mcatnlo_str . o 
mcatnlo_pdf tomlm. o mcatnlo_libof pdf . o dummies. o SYSFILE 

• NLO with PDFLIB: mcatnlo_vbmain . o mcatnlo_vbxsec . o mcatnlo_helas2 . o 
mcatnlo_date . o mcatnlo_int . o mcatnlo_uxdate . o mcatnlo_uti . o mcatnlo_str . o 
mcatnlo_mlmtopdf .o dummies . o SYSFILE CERNLIB 

• NLO with LHAPDF: mcatnlo_vbmain . o mcatnlo_vbxsec . o mcatnlo_helas2 . o 
mcatnlo_date . o mcatnlo_int . o mcatnlo_uxdate . o mcatnlo_lhauti . o mcatnlo_str . o 
mcatnlo_mlmtolha. o dummies . o SYSFILE LHAPDF 

• MC with private PDFs: mcatnloJiwdriver . o mcatnlo Jiwlhin . o mcatnloJiwanvbp . o 
mcatnloJibook. o mcatnlo_str . o mcatnlo_pdf tomlm. o mcatnlo_libof pdf . o dummies. o 
HWUTI HERWIGVER 

• MC with PDFLIB: mcatnloJiwdriver . o mcatnloJiwlhin.o mcatnloJiwanvbp . o 
mcatnloJibook. o mcatnlo_str . o mcatnlojnlmtopdf . o dummies . o HWUTI HERWIGVER 
CERNLIB 

• MC with LHAPDF: mcatnloJiwdriver . o mcatnlo Jiwlhin . o mcatnloJiwanvbp . o 
mcatnloJibook. o mcatnlo_str . o mcatnlojnlmtolha. o dummies . o HWUTI HERWIGVER 
LHAPDF 

The process-specific codes mcatnlo_vbmain . o and mcatnlo_vbxsec . o (for the NLO exe- 
cutable) and mcatnloJiwanvbp . o (the HERWIG analysis routines in the MC executable) 
need to be replaced by their analogues for other production processes, which can be easily 
read from the list given in sect. 1.2. 

The variable SYSFILE must be set either equal to alpha . o, or to linux . o, or to sun . o, 
according to the architecture of the machine on which the run is performed. For any other 
architecture, the user should provide a file corresponding to alpha. f etc., which he/she 
will easily obtain by modifying alpha. f. The variables HWUTI and HERWIGVER have been 
described in sect. 4. In order to create the object files eventually linked, static compilation 
is always recommended (for example, g77 -Wall -fno-automatic on Linux). 
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B.2 The input files 

In this appendix, we describe the inputs to be given to the NLO and MC executables in the 
case of vector boson pair production. The case of other production processes is completely 
analogous. When the shell scripts are used to run the MC@NLO, two files are created, 
FPREFIXNLOinput and FPREFIXMCinput, which are read by the NLO and MC executable 
respectively. We start by considering the inputs for the NLO executable, presented in 
table 2. The variables whose name is in uppercase characters have been described in 



'FPREFIX' 


! prefix for BASES files 


'EVPREFIX' 


! prefix for event files 


ECM FFACT FREN FFACTMC FRENMC 


! energy, scalefactors 


IPRDC 


! -2850/60/70/80=WW/ZZ/ZW+/ZW- 


WMASS ZMASS 


! M_W, M_Z 


UMASS DMASS SMASS CMASS BMASS GMASS 


! quark and gluon masses 


'PARTI' 'PART2' 


! hadron types 


'PDFGROUP' PDFSET 


! PDF group and id number 


LAMBDAFIVE 


! Lambda_5, <0 for default 


'SCHEMEOFPDF' 


! scheme 


NEVENTS 


! number of events 


WGTTYPE 


! => wgt=+l/-l, 1 => wgt=+w/-w 


RNDEVSEED 


! seed for rnd numbers 


zi 


! zi 


nitni nitn2 


! itmxl,itmx2 



Table 2: Sample input file for the NLO code (for vector boson pair production). FPREFIX and 
EVPREFIX must be understood with SCRTCH in front (see sect. 4). 

sect. 4. The other variables are assigned by the shell script. Their default values are given 
in table 3. Users who run the package without the script should use the values given 



Variable 


Default value 


zi 


0.2 


nitnj 


10/0 (BASES=0N/0FF) 



Table 3: Default values for script-generated variables in FPREFIXNLOinput. 

in table 3. The variable zi controls, to a certain extent, the number of negative-weight 
events generated by the MC@NLO (see ref. [1]). Therefore, the user may want to tune this 
parameter in order to reduce as much as possible the number of negative-weight events. 
We stress that the MC code will not change this number; thus, the tuning can (and must) 
be done only by running the NLO code. The variables nitnj control the integration step 
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(see sect. 3.1), which can be skipped by setting nitnj = 0. If one needs to perform the 
integration step, we suggest setting these variables as indicated in table 3. 



hvrHhr 1a . events 


! event file 


NEVENTS 


! number of events 


pdf type 


! 0->Herwig PDFs, 1 otherwise 


PARTI PART2 


! hadron types 


beammom beammom 


! beam momenta 


IPROC 


! -2850/60/70/80=WW/ZZ/ZW+/ZW- 


'PDFGROUP' 


! PDF group (1) 


PDFSET 


! PDF id number (1) 


'PDFGROUP' 


! PDF group (2) 


PDFSET 


! PDF id number (2) 


LAMBDAHERW 


! Lambda_5, <0 for default 


WMASS WMASS ZMASS 


! M_W+, M_W-, M_Z 


UMASS DMASS SMASS CMASS BMASS GMASS 


! quark and gluon masses 



Table 4: Sample input file for the MC code (for vector boson pair production), resulting from 
setting HERPDF=EXTPDF, which implies pdf type=l. Setting HERPDF=DEFAULT results in an analogous 
file, with pdf type=0, and without the lines concerning PDFGROUP and PDFSET. EVPREFIX must be 
understood with SCRTCH in front (see sect. 4). The negative sign of IPROC tells HERWIG to use 
Les Houches interface routines. 

We now turn to the inputs for the MC executable, presented in table 4. The variables 
whose names are in uppercase characters have been described in sect. 4. The other variables 
are assigned by the shell script. Their default values are given in table 5. The user can 



Variable 


Default value 


esctype 





pdf type 


0/1 (HERPDF=DEFAULT/EXTPDF) 


beammom 


EMC/2 



Table 5: Default values for script-generated variables in MCinput. 

freely change the values of esctype and pdf type; on the other hand, the value of beammom 
must always be equal to half of the hadronic CM energy. 

When LHAPDF is linked, the value of PDFSET is sufficient to identify the parton 
density set. In such a case, PDFGROUP must be set in input equal to LHAPDF if the user 
wants to freeze the PDFs at the boundaries (defined as the ranges in which the fits have 
been performed). If one chooses to extrapolate the PDFs across the boundaries, one should 
set PDFGROUP=LHAEXT in input. 
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In the case of j/Z, W^, Higgs or heavy quark production, the MC executable can 
be run with the corresponding positive input process codes IPROC = 1350, 1399, 1499, 
1600+ID, 1705, 1706, 2000-2008, 2600+ID or 2700+ID, to generate a standard HERWIG 
run for comparison purposes 4 . Then the input event file will not be read: instead, parton 
configurations will be generated by HERWIG according to the LO matrix elements. 
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